Previous Next Contents Generated Index Doc Set



CHAPTER 6 : Event Bindings


Introduction

All objects within your Visaj design can be linked together using events. Events are messages which can be sent by the action of one component and may be received by the method of another. You can specify that a particular method in a specific component is called when an action (such as a button press) occurs in one component. Once you have created an event binding in Visaj, it is immediately active in the dynamic display. You can create as many bindings as you wish and try them out straightaway.

The Event Binding Editor, described in the following section, lets you create new bindings and edit existing ones. This is a wizard which can be displayed in one of the following ways:

  1. Pressing the    icon on the toolbar.
  2. Holding down the Alt or Control key while dragging from the source to the destination component.
  3. Choosing "Add event binding" from the Method menu.
  4. Pressing either "New" or "Edit" beneath the Event bindings list.

Event bindings, once created, are listed on the Event bindings tab of the method editing area. Here they may be edited, re-ordered or deleted. The Event bindings list is described in the Event Bindings List section on page 86.


Event Binding Editor

The Event Binding Editor, shown in Figure 6-1, is where new bindings are created and existing ones are edited.

Displaying the Editor

There are five ways to display the Event Binding Editor:

  1. With the Alt or Control key held down, drag the mouse pointer from one component to another in the containment hierarchy. The Event Binding Editor then appears, primed with the first and second component as the source and destination of the binding respectively. The first event type in the list is also selected. This method can only be used to create new bindings.
  2. Press the Event Binding Editor button    on the toolbar. The Editor is ready for you to create a new binding so it does not pre-select anything, unless a component is selected on the Beans page. The component is then used as the Source Object.
  3. Press "New" in the Event Bindings List. The Event Binding Editor is not primed, except to show all the available components.
  4. Press "Edit" in the Event Bindings List. You will need to select a binding from the Event Bindings List first.
  5. Select the "Add event binding" item in the Method menu. This is exactly the same as pressing the corresponding toolbar button.

Description of the Editor

The event binding editor shows all the components in your design, all the event types associated with the selected source component and all methods available for the selected destination component. You must make a selection in the "Source" and "Object" lists for the "Type" and "Method" lists to appear.

There are usually a large number of methods for a particular handler. To quickly locate the one you require, select the Method pane (by selecting any method within it) and type the first letters of the method you are looking for. The display scrolls to methods beginning with the letters you type.

Some handler methods may be capable of throwing an exception. This is not indicated in the event binding editor. However, if you add an event binding with one of these methods, Visaj adds a method to your class which handles the exception when thrown. The method is displayed in the class structure editor on the right of the Visaj window but its signature cannot be changed. In the generated code, this method gives you a place to add your own code for handling exceptions.

Assignment

The first item in the Method list is not a method at all. This item, shown as "= [expression]", allows you to assign a property or method return value to the "Object" when an event is fired. The "Next" button becomes enabled when the assignment operator is selected. Press this button to display the parameters page of the editor - described in more detail in the Event Binding Editor: Parameters section on page 83. You should use the parameters page exactly as described even though you are specifying the source of an assignment rather than a method parameter. Remember that, as with parameters, you can only select a method return value or property which is the appropriate type. You may set a "Value" if there is an editor available for the selected type.

Figure  6-1 Event Binding Editor

At the bottom of the Event Binding Editor there are five buttons: "Cancel", "<Previous", "Next>", "Finish" and "Another". The Finish and Another buttons become sensitive only when you have entered enough information for the binding to be created. The only difference between these two buttons is that pressing Finish closes the dialog whereas pressing Another leaves the dialog open on the screen.

When you select a destination method, the Next button becomes sensitive if the method has parameters. Pressing the Next button (or the Return key) displays the second page of the Event Binding Editor, as shown in Figure 6-2.

Figure  6-2 Parameters Page of Event Binding Editor


Event Binding Editor: Parameters

The second page of the Event Binding Editor allows you to specify values for the parameters to the destination method. The parameters are listed by their type on the left of the dialog. Each parameter is shown with a cross or tick next to it:

   A value has been set for this parameter

   No value has been set for this parameter

The right of the dialog contains two areas. The top area lists the ways of specifying the value of the selected parameter. The lower area contains the editor for the selected value type. The four value types are:

  1. Property
  2. Method
  3. Value
  4. Code expression

The following sub-sections describes each of the above.

Property

This allows you to set the value of the parameter to the value of a component's property. When "Property" is selected, two scrolling lists appear in the lower area. This is shown in Figure 6-3.

Figure  6-3 Property Value for Parameter

The list on the left shows all the objects in your design, including the event object being passed to the listener method. Selecting one of these objects causes all the properties of this object to be displayed in the list on the right if, and only if, it is assignable to the selected parameter.

You can assign any property to a parameter of type String as all objects are converted to Strings by way of their "toString" method. Properties which are going to be coerced in this way are shown in blue type.

The property list includes "this" if the object selected from the object list can be assigned to the selected parameter.

If the object selected from the object list has no properties of the appropriate type, the message "No properties of an appropriate type" is shown in the property list.

This type of parameter value is reflected in the dynamic display as soon as the binding has been completed, except when event objects have been selected from the object list.

Method

This option allows you to use the return value of another method in your design. When you select "Method", a text field, a button labelled "Edit" and the Method selection dialog appears. The Method Selector is shown in Figure 6-4. When you have finished selecting a method it is shown in the text field. To display the Method Selector in order to edit a previous selection, press the "Edit" button.

Figure  6-4 Method Selection Dialog

The left side of this dialog lists all the objects in your design. When you select an object, the area on the right lists object methods which return the same type as the selected parameter. For example, if you have selected a parameter of type "int", only methods which return an integer are listed. One of the objects which can be selected is "this" - the class currently being designed. If you have added a method to your class with a compatible return type, you will be able to select it as the method for the event binding.

If the selected method has parameters, the Next button is enabled. Pressing Next displays the parameters page of the Method selection dialog - this is identical to the parameters page of the Event binding editor and is used in exactly the same way.

Press Finish when you have selected a method or Cancel if you wish to close the dialog without selecting a method. You cannot continue working on your event binding until the Method selection dialog has been closed. The selected method is shown in the text field of the parameters page.

Value

This is an explicit value. When this is selected, a property editor appears in the lower area for you to set the value. If the property editor is a text field, you must press the Return key after typing the text to set the value. These values are used in the dynamic display once the binding has been completed.

Code Expression

This allows you to type in an arbitrary value or expression for the parameter. Bindings which use these are not active in the dynamic display. A text box appears in the lower area for you to enter the code expression. You do not need to press the return key at the end of the text.


Event Bindings List

The Event Bindings List, shown in Figure 6-5, makes up part of the method editing tools in the Class Editor. To view the Events Binding List, select a method from the class structure view and choose the "Event bindings" pane from the tabbed panel. Until you define a binding, this list is empty.

Figure  6-5 Currently Defined Event Bindings

Press "New" to populate this list, "Edit" to change the selected binding and "Delete" to remove it from the list.

Order of List

If you have more than one method bound to a component's event, they are grouped together. Use the "Up" and "Down" buttons to re-order the methods within a particular component/event group. This order is significant because this is the order in which the event bindings are executed when the application runs. The generated code always reflects the order presented in this list. To make sure that the dynamic display also reflects any changes you may have made, rebuild the containment hierarchy by pressing the Reset button.


Invalid Bindings

An event binding is marked as "INVALID" if the source or destination object of a binding has been removed from the design after the binding was created. The invalid part of the binding is shown in red. An example invalid binding is shown in Figure 6-6.

Figure  6-6 Invalid Event Binding

The binding remains intact, so if you paste the lost object back into the design (or press "Undo"), the binding is automatically revalidated.




Previous Next Contents Generated Index Doc Set

Copyright © 1998, 1999 Pacific Imperial Inc., TakeFive Software Inc. All Rights Reserved.